Refactor: Modularize CLI Architecture and Add Hooks Support

Overview

This PR represents a major architectural refactoring of uvtask, transforming the monolithic CLI implementation into a modular, testable architecture while adding new features and infrastructure improvements.

🏗️ Architecture Refactoring

Modular Design

The monolithic cli.py file (847 lines) has been split into focused, single-responsibility modules:

• colors.py: Color management and terminal output formatting

  • Centralized color preference management
  • Support for --color flag (auto/always/never)
  • Terminal capability detection

• commands.py: Command execution and script loading

  • Script discovery from pyproject.toml
  • Command execution orchestration
  • Hook integration

• config.py: Configuration parsing and pyproject.toml handling

  • PyProjectReader for TOML parsing
  • Script value parsing (string, list, table formats)
  • Version loading

• executor.py: Command execution with quiet/verbose support

  • Subprocess execution
  • Quiet/verbose output handling
  • Exit code management

• formatters.py: Custom argparse formatters and help text processing

  • CustomHelpFormatter matching uv CLI style
  • Command similarity matching for better error messages
  • Help text processing and formatting

• hooks.py: Pre/post hook discovery and validation

  • Hook name generation (Composer/NPM styles)
  • Style consistency validation
  • Hook command extraction

• parser.py: Argument parsing and CLI builder

  • Global options parsing
  • Subparser creation
  • Argument parser building

Benefits

• ✅ Improved maintainability through separation of concerns
• ✅ Enhanced testability with isolated modules
• ✅ Better code organization and readability
• ✅ Easier to extend with new features

✨ New Features

Pre/Post Hooks Support

Added comprehensive hook functionality supporting both naming conventions:

Composer-style hooks:

[tool.run-script]
pre-test = "echo 'Running tests...'"
test = "pytest"
post-test = "echo 'Tests completed!'"

NPM-style hooks:

[tool.run-script]
pretest = "echo 'Running tests...'"
test = "pytest"
posttest = "echo 'Tests completed!'"

Features:

• Automatic hook discovery and execution
• Style consistency validation (prevents mixing Composer and NPM styles)
• --no-hooks and --ignore-scripts flags to skip hooks
• Support for list-based hook commands

🚀 Infrastructure

CI/CD Pipelines

Added GitHub Actions workflows for automated testing and deployment:

CI Pipeline (ci.yml):

• Runs on push, pull requests, and manual dispatch
• Executes security analysis (licenses, vulnerabilities)
• Runs static analysis (linter, type checking)
• Executes unit and integration tests
• Multi-platform support (linux/amd64, linux/arm64)

CD Pipeline (cd.yml):

• Automated versioning and tagging
• Package building and publishing
• Artifact management
• Triggered after successful CI runs on main branch

🧪 Testing

Comprehensive Test Coverage

Added unit tests for all new modules:

• test_cli.py: CLI integration and end-to-end tests
• test_commands.py: Command execution and script loading tests
• test_config.py: Configuration parsing and TOML handling tests
• test_executor.py: Command executor with quiet/verbose mode tests
• test_formatters.py: Help formatter and argument parsing tests
• test_hooks.py: Hook discovery, validation, and execution tests
• test_parser.py: Argument parser and CLI builder tests

📚 Documentation

• Updated README with hooks examples
• Improved quick start guide
• Enhanced configuration examples

🔄 Backward Compatibility

All changes maintain backward compatibility:

• Existing CLI commands work unchanged
• Configuration format remains the same
• No breaking changes to public API

📦 Dependencies

• Updated ty package from 0.0.6 to 0.0.7

🎯 Impact

• Code Quality: Significantly improved through modular architecture
• Maintainability: Easier to understand, modify, and extend
• Testability: Comprehensive test coverage for all components
• Developer Experience: Better error messages and help text
• Feature Set: Added hooks support for workflow automation

Testing

• All existing tests pass
• New unit tests added and passing
• Integration tests verified
• Manual CLI testing completed
• Hooks functionality tested with both naming styles

Checklist

• Code follows project style guidelines
• Tests added/updated
• Documentation updated
• Backward compatibility maintained
• CI/CD pipelines configured
• No breaking changes introduced